---
id: select
title: Select
description: Displays a list of options for the user to pick from.
---

<ComponentPreview id="Select" />

## Anatomy

To set up the select correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="select" />

## Examples

Learn how to use the `Select` component in your project. Let's take a look at the most basic example:

<Example id="basic" />

### Controlled Value

Use the `value` and `onValueChange` props to control the selected items.

<Example id="controlled" />

### Grouping

Grouping related options can be useful for organizing options into categories.

- Use the `groupBy` prop to configure the grouping of the items.
- Use the `collection.group()` method to get the grouped items.
- Use the `Select.ItemGroup` and `Select.ItemGroupLabel` components to render the grouped items.

<Example id="grouping" />

### Multiple Selection

To enable `multiple` item selection:

<Example id="multiple" />

### Form Library

Here's an example of integrating the `Select` component with a form library.

<Example id="form-library" />

### Field Component

The `Field` component helps manage form-related state and accessibility attributes of a select. It includes handling
ARIA labels, helper text, and error text to ensure proper accessibility.

<Example id="with-field" />

### Async Loading

Here's an example of how to load the items asynchronously when the select is opened.

<Example id="async" />

### Root Provider

The `RootProvider` component provides a context for the select. It accepts the value of the `useSelect` hook. You can
leverage it to access the component state and methods from outside the select.

<Example id="root-provider" />

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

### Select on Highlight

Here's an example of automatically selecting items when they are highlighted (hovered or navigated to with keyboard).

<Example id="select-on-highlight" />

### Maximum Selected Items

Here's an example of limiting the number of items that can be selected in a multiple select.

<Example id="max-selected" />

### Lazy Mount

The `lazyMount` and `unmountOnExit` props allow you to control when the select content is mounted and unmounted from the
DOM. This can improve performance by only rendering the content when needed.

<Example id="lazy-mount" />

## Guides

### Type-Safety

The `Select.RootComponent` type enables you to create closed, strongly typed wrapper components that maintain full type
safety for collection items.

This is particularly useful when building reusable select components with custom props and consistent styling.

```tsx
import { Select as ArkSelect, type CollectionItem } from '@ark-ui/react/select'
import { createListCollection } from '@ark-ui/react/collection'

interface SelectProps<T extends CollectionItem> extends ArkSelect.RootProps<T> {}

const Select: ArkSelect.RootComponent = (props) => {
  return <ArkSelect.Root {...props}>{/* ... */}</ArkSelect.Root>
}
```

Then, you can use the `Select` component as follows:

```tsx
const App = () => {
  const collection = createListCollection({
    initialItems: [
      { label: 'React', value: 'react' },
      { label: 'Vue', value: 'vue' },
      { label: 'Svelte', value: 'svelte' },
    ],
  })
  return (
    <Select
      collection={collection}
      onValueChange={(e) => {
        // this will be strongly typed Array<{ label: string, value: string }>
        console.log(e.items)
      }}
    >
      {/* ... */}
    </Select>
  )
}
```

### Usage in Popover or Dialog

When using the Select component within a `Popover` or `Dialog`, avoid rendering its content within a `Portal` or
`Teleport`.

This ensures the Select's content stays within the Popover/Dialog's DOM hierarchy rather than being portalled to the
document body, maintaining proper interaction and accessibility behavior.

### Hidden Select

The `Select.HiddenSelect` component renders a native HTML `<select>` element that's visually hidden but remains in the
DOM. This component is essential for:

- **Form submission**: Native form submission and serialization work seamlessly since the actual `<select>` element
  exists in the DOM
- **Browser auto-fill**: Browsers can properly auto-fill the select based on previously submitted form data
- **Progressive enhancement**: Forms remain functional even if JavaScript fails to load

```tsx
<Select.Root>
  <Select.HiddenSelect />
  {/* Other Select components */}
</Select.Root>
```

The hidden select automatically syncs with the Select component's value, ensuring form data is always up-to-date.

### Empty State

You can create an empty state component that displays when there are no items in the collection. Use the
`useSelectContext` hook to check the collection size:

```tsx
const SelectEmpty = (props: React.ComponentProps<'div'>) => {
  const select = useSelectContext()
  if (select.collection.size === 0) {
    return <div {...props} role="presentation" />
  }
  return null
}
```

Then use it within your Select content:

```tsx
<Select.Content>
  <SelectEmpty>No items to display</SelectEmpty>
  {/* Your items */}
</Select.Content>
```

### Available height and width

The following css variables are exposed to the `Select.Positioner` which you can use to style the `Select.Content`

```css
/* width of the select trigger */
--reference-width: <pixel-value>;
/* width of the available viewport */
--available-width: <pixel-value>;
/* height of the available viewport */
--available-height: <pixel-value>;
```

For example, if you want to make sure the maximum height doesn't exceed the available height, you can use the following:

```css
[data-scope='select'][data-part='content'] {
  max-height: calc(var(--available-height) - 100px);
}
```

## API Reference

### Props

<ComponentTypes id="select" />

### Context

These are the properties available when using `Select.Context`, `useSelectContext` hook or `useSelect` hook.

<ContextType id="select" />

## Accessibility

Complies with the [Listbox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).

### Keyboard Support

<KeyBindingsTable id="select" />
